feat(proposals): Proposal Acceptance & Contract Creation Service - #229

Overview

Implements the Proposal Acceptance & Contract Creation Service so that when a client accepts a freelancer proposal, TaskChain atomically creates the linked contract, seeds milestones, and initializes escrow as Pending Funding — with rollback on any failure.

Related Issue

Closes #217

Changes

Proposal acceptance service

• [ADD] lib/proposals/types.ts

  • Domain types for proposals, jobs, contracts, milestones, audit events, and the repository interface.

• [ADD] lib/proposals/errors.ts

  • Typed errors (ProposalNotFound, ProposalAlreadyAccepted, ProposalForbidden, …) plus proposalErrorToHttpStatus.

• [ADD] lib/proposals/repository.ts

  • Neon SQL repository using sql.begin so accept → contract → milestones → escrow init + audit writes commit in one transaction.

• [ADD] lib/proposals/service.ts

  • Orchestration: client-only auth, job/proposal validation, one-accepted-proposal / one-contract-per-job guards, milestone budget checks, then atomic commit.

• [ADD] lib/proposals/index.ts

  • Public barrel exports for API routes and tests.

Persistence & API

• [ADD] scripts/013-proposal-acceptance.sql / lib/db/migrations/013_proposal_acceptance.sql

  • proposal_id on contracts (unique), milestone_breakdown on proposals, partial unique index for one accepted proposal per job, proposal_acceptance_audit table.

• [ADD] app/api/proposals/[id]/accept/route.ts

  • Authenticated POST endpoint; freelancers are rejected; returns contract, milestones, escrow status, and audit event names.

Tests

• [ADD] __tests__/proposals/accept-service.test.ts
  • Coverage for happy path, client-only auth, non-pending / closed job, duplicate accepted proposal & contract, milestone budget validation, default milestone, and transaction rollback surfacing.

Verification Results

Implemented via GitHub Contents/Git API (no local clone).
Acceptance criteria mapping:
✅ Database transaction for atomicity — sql.begin wraps all writes; failures raise ProposalTransactionError
✅ Prevent multiple accepted proposals per project — service guard + UNIQUE INDEX WHERE status='accepted'
✅ Maintain proposal → contract relationship — contracts.proposal_id + unique index
✅ Status updates — proposal → accepted; contract → pending (Draft/Pending Funding); escrow_status → pending
✅ Error handling — transaction rollback on commit failure; typed HTTP errors from API route
✅ Authorization — only job client (non-freelancer) may accept
✅ Audit trail — proposal_accepted, contract_created, milestones_created, escrow_initialized